NAIE» Navigation and Ancillary Information Facility 


Using Module Headers 


October 2022 


Topics 


Navigation and Ancillary Information Facility 


¢ Module* Header Purpose 

¢ FORTRAN Module Header Locations 
¢ C Module Header Locations 

¢ Icy Module Header Locations 

¢ Mice Module Header Locations 

¢ Examine a Typical Header 


* “Module” = API, routine, subroutine, procedure, function 
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Module Header Purpose 
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¢ NAIF uses module “headers” to provide detailed 
information describing how to use the module 


— In FORTRAN, C and MATLAB Toolkits the “headers” are comment 
blocks inserted in the source code 


— In IDL Toolkits, where there are (currently) no source code files, the 
“headers” exist as independent files 


¢ All Toolkit distributions include hyperlinked HTML 
versions of the module headers. 


— All but ICY also include plain text versions 


¢ The next charts provide the header contents and 
locations 
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Module Header Contents 
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Procedure or subroutine name 

Brief abstract 

Disclaimer (legalese required for JPL code; in Fortran, C, and Matlab) 

Required Reading (names of any related SPICE technical reference documents) 
Keywords (single relevant words; in Fortran and C; not really used) 

Argument type declarations, or Include files 

Brief Input and Output descriptions 

Detailed Input descriptions 

Detailed Output descriptions 

Parameter definitions, if any 

Exceptions (what happens if a problem is detected) 

Descriptions of any files used 

Particulars (details about what the module does, how it works, any limitations) 
Code usage example(s) 

Restrictions in usage of the module 

Literature references 

Author 

Version 

Index entries (brief phrases used to generate entries for the Permuted Index document) 
Revision history (in Fortran) 


The source code goes here! 
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Fortran Module Header Locations 
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¢ Plain text versions: 
— <path to SPICELIB>/toolkit/src/spicelib/<name.f> or <name>.for 


— In most cases there is a single “header” at the top of the source 
code. For cases where a FORTRAN module has multiple entry 
points, there are additional “headers” at each entry point. For 
example: 


» “keeper.f” has entries for: 
¢ FURNSH, KTOTAL, KINFO, KDATA, KCLEAR, and UNLOAD 


¢ HTML versions: 
— <path to SPICELIB>/toolkit/doc/html/spicelib/index.html 
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NAIE> C Module Header Locations 
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¢ Plain text versions: 
— <path to CSPICE>/cspice/src/cspice/<name>_c.c 


¢ HTML versions: 
— <path to CSPICE>/cspice/doc/html/cspice/index.html 
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IDL Module Header Locations 
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¢ Two sets of headers are provided 
— Icy headers in HTML format: 
» <path to Icy>/icy/doc/html/icy/index.html 
— CSPICE headers, in text and HTML formats: 
» <path to Icy>/icy/src/cspice/<name>_c.c 
» <path to Icy>/icy/doc/html/cspice/index.html 


¢ The information provided in an “Icy” header is 
minimal in some cases; the corresponding CSPICE 
header provides more detail 


— Alink to the corresponding CSPICE header is provided in the Icy 
header 
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Matlab Module Header Locations 
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¢ Two sets of headers are provided 
— Mice headers in HTML format: 


» <path to Mice>/mice/doc/html/mice/index.html 


» Also available using the Matlab help command, e.g.: 
no ele CSe.ce shrvet 


— CSPICE headers, in text and HTML formats: 
» <path to Mice>/mice/src/cspice/<name>_c.c 
» <path to Mice>/mice/doc/html/cspice/index.html 


¢ The information provided in a “Mice” header is 
minimal in some cases; the corresponding CSPICE 
header provides more detail 


—A en to the corresponding CSPICE header is provided in the Mice 
header 
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NAIE> Examine a Typical Header 
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¢ As example, look for and examine the headers for the 
modules named spkezr and str2et 


FORTRAN IDL (Icy) | MATLAB (Mice) 


srcezn [stone [ester [este ster 


STR2ET cspice_str2et cspice_str2et 


spkezr is the principal ephemeris access module 
str2et is a key time conversion module 
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